<html><!-- Created using the cpp_pretty_printer from the dlib C++ library.  See http://dlib.net for updates. --><head><title>dlib C++ Library - fine_hog_image_abstract.h</title></head><body bgcolor='white'><pre>
<font color='#009900'>// Copyright (C) 2012  Davis E. King (davis@dlib.net)
</font><font color='#009900'>// License: Boost Software License   See LICENSE.txt for the full license.
</font><font color='#0000FF'>#undef</font> DLIB_FINE_HOG_IMaGE_ABSTRACT_Hh_
<font color='#0000FF'>#ifdef</font> DLIB_FINE_HOG_IMaGE_ABSTRACT_Hh_

<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../array2d.h.html'>../array2d.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='../matrix.h.html'>../matrix.h</a>"
<font color='#0000FF'>#include</font> "<a style='text-decoration:none' href='hog_abstract.h.html'>hog_abstract.h</a>"


<font color='#0000FF'>namespace</font> dlib
<b>{</b>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> cell_size_,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> block_size_,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> pixel_stride_,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>char</u></font> num_orientation_bins_,
        <font color='#0000FF'><u>int</u></font>           gradient_type_
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'>class</font> <b><a name='fine_hog_image'></a>fine_hog_image</b> : noncopyable
    <b>{</b>
        <font color='#009900'>/*!
            REQUIREMENTS ON TEMPLATE PARAMETERS 
                - cell_size_ &gt; 1
                - block_size_ &gt; 0
                - pixel_stride_ &gt; 0
                - num_orientation_bins_ &gt; 0
                - gradient_type_ == hog_signed_gradient or hog_unsigned_gradient

            INITIAL VALUE
                 - size() == 0

            WHAT THIS OBJECT REPRESENTS
                This object is a version of the hog_image that allows you to extract HOG
                features at a finer resolution.  The hog_image can only extract HOG features
                cell_size_ pixels apart.  However, this object, the fine_hog_image can 
                extract HOG features from every pixel location.

                The template arguments to this class have the same meaning as they do for
                the hog_image, except for pixel_stride_.  This controls the stepping between
                HOG extraction locations.  A value of 1 indicates HOG features should be
                extracted from every pixel location.  A value of 2 indicates every other pixel
                location, etc.

                Finally, note that the interpolation used by this object is equivalent
                to using hog_angle_interpolation with hog_image.  

            THREAD SAFETY
                Concurrent access to an instance of this object is not safe and should be protected
                by a mutex lock except for the case where you are copying the configuration 
                (via copy_configuration()) of a fine_hog_image object to many other threads.  
                In this case, it is safe to copy the configuration of a shared object so long
                as no other operations are performed on it.
        !*/</font>

    <font color='#0000FF'>public</font>:

        <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> cell_size <font color='#5555FF'>=</font> cell_size_;
        <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> block_size <font color='#5555FF'>=</font> block_size_;
        <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> pixel_stride <font color='#5555FF'>=</font> pixel_stride_;
        <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> num_orientation_bins <font color='#5555FF'>=</font> num_orientation_bins_;
        <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>int</u></font>           gradient_type <font color='#5555FF'>=</font> gradient_type_;

        <font color='#0000FF'>const</font> <font color='#0000FF'>static</font> <font color='#0000FF'><u>long</u></font> min_size <font color='#5555FF'>=</font> cell_size<font color='#5555FF'>*</font>block_size<font color='#5555FF'>+</font><font color='#979000'>2</font>;

        <font color='#0000FF'>typedef</font> matrix<font color='#5555FF'>&lt;</font><font color='#0000FF'><u>double</u></font>, block_size<font color='#5555FF'>*</font>block_size<font color='#5555FF'>*</font>num_orientation_bins, <font color='#979000'>1</font><font color='#5555FF'>&gt;</font> descriptor_type;

        <b><a name='fine_hog_image'></a>fine_hog_image</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - this object is properly initialized
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='clear'></a>clear</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - this object will have its initial value
        !*/</font>

        <font color='#0000FF'><u>void</u></font> <b><a name='copy_configuration'></a>copy_configuration</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> fine_hog_image<font color='#5555FF'>&amp;</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - copies all the state information of item into *this, except for state 
                  information populated by load().  More precisely, given two fine_hog_image 
                  objects H1 and H2, the following sequence of instructions should always 
                  result in both of them having the exact same state.
                    H2.copy_configuration(H1);
                    H1.load(img);
                    H2.load(img);
        !*/</font>

        <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
            <font color='#0000FF'>typename</font> image_type
            <font color='#5555FF'>&gt;</font>
        <font color='#0000FF'>inline</font> <font color='#0000FF'><u>void</u></font> <b><a name='load'></a>load</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> image_type<font color='#5555FF'>&amp;</font> img
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            requires
                - image_type is a dlib::matrix or something convertible to a matrix
                  via mat()
                - pixel_traits&lt;typename image_traits&lt;image_type&gt;::pixel_type&gt;::has_alpha == false
            ensures
                - if (img.nr() &lt; min_size || img.nc() &lt; min_size) then
                    - the image is too small so we don't compute anything on it
                    - #size() == 0
                - else
                    - generates a HOG image from the given image.   
                    - #size() &gt; 0
        !*/</font>

        <font color='#0000FF'>inline</font> <font color='#0000FF'><u>void</u></font> <b><a name='unload'></a>unload</b><font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font>;
        <font color='#009900'>/*!
            ensures
                - #nr() == 0
                - #nc() == 0
                - clears only the state information which is populated by load().  For 
                  example, let H be a fine_hog_image object.  Then consider the two 
                  sequences of instructions:
                    Sequence 1:
                        H.load(img);      
                        H.unload();
                        H.load(img);

                    Sequence 2:
                        H.load(img);
                  Both sequence 1 and sequence 2 should have the same effect on H.  
        !*/</font>

        <font color='#0000FF'>inline</font> <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> <b><a name='size'></a>size</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns nr()*nc()
        !*/</font>

        <font color='#0000FF'>inline</font> <font color='#0000FF'><u>long</u></font> <b><a name='nr'></a>nr</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns the number of rows in this HOG image
        !*/</font>

        <font color='#0000FF'>inline</font> <font color='#0000FF'><u>long</u></font> <b><a name='nc'></a>nc</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns the number of columns in this HOG image
        !*/</font>

        <font color='#0000FF'><u>long</u></font> <b><a name='get_num_dimensions'></a>get_num_dimensions</b> <font face='Lucida Console'>(</font>
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns the number of dimensions in the feature vectors generated by
                  this object.  
                - In particular, returns the value block_size*block_size*num_orientation_bins
        !*/</font>

        <font color='#0000FF'>inline</font> <font color='#0000FF'>const</font> descriptor_type<font color='#5555FF'>&amp;</font> <b><a name='operator'></a>operator</b><font face='Lucida Console'>(</font><font face='Lucida Console'>)</font> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>long</u></font> row,
            <font color='#0000FF'><u>long</u></font> col
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            requires
                - 0 &lt;= row &lt; nr()
                - 0 &lt;= col &lt; nc()
            ensures
                - returns the descriptor for the HOG block at the given row and column.  This descriptor 
                  will include information from a window that is located at get_block_rect(row,col) in
                  the original image given to load().
                - The returned descriptor vector will have get_num_dimensions() elements.
        !*/</font>

        <font color='#0000FF'>const</font> rectangle <b><a name='get_block_rect'></a>get_block_rect</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'><u>long</u></font> row,
            <font color='#0000FF'><u>long</u></font> col
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns a rectangle that tells you what part of the original image is associated
                  with a particular HOG block.  That is, what part of the input image is associated
                  with (*this)(row,col).
                - The returned rectangle will be cell_size*block_size pixels wide and tall.
        !*/</font>

        <font color='#0000FF'>const</font> point <b><a name='image_to_feat_space'></a>image_to_feat_space</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> point<font color='#5555FF'>&amp;</font> p
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - Each local feature is extracted from a certain point in the input image.
                  This function returns the identity of the local feature corresponding
                  to the image location p.  Or in other words, let P == image_to_feat_space(p), 
                  then (*this)(P.y(),P.x()) == the local feature closest to, or centered at, 
                  the point p in the input image.  Note that some image points might not have 
                  corresponding feature locations.  E.g. border points or points outside the 
                  image.  In these cases the returned point will be outside get_rect(*this).
        !*/</font>

        <font color='#0000FF'>const</font> rectangle <b><a name='image_to_feat_space'></a>image_to_feat_space</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> rect
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns rectangle(image_to_feat_space(rect.tl_corner()), image_to_feat_space(rect.br_corner()));
                  (i.e. maps a rectangle from image space to feature space)
        !*/</font>

        <font color='#0000FF'>const</font> point <b><a name='feat_to_image_space'></a>feat_to_image_space</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> point<font color='#5555FF'>&amp;</font> p
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - returns the location in the input image space corresponding to the center
                  of the local feature at point p.  In other words, this function computes
                  the inverse of image_to_feat_space().  Note that it may only do so approximately, 
                  since more than one image location might correspond to the same local feature.  
                  That is, image_to_feat_space() might not be invertible so this function gives 
                  the closest possible result.
        !*/</font>

        <font color='#0000FF'>const</font> rectangle <b><a name='feat_to_image_space'></a>feat_to_image_space</b> <font face='Lucida Console'>(</font>
            <font color='#0000FF'>const</font> rectangle<font color='#5555FF'>&amp;</font> rect
        <font face='Lucida Console'>)</font> <font color='#0000FF'>const</font>;
        <font color='#009900'>/*!
            ensures
                - return rectangle(feat_to_image_space(rect.tl_corner()), feat_to_image_space(rect.br_corner()));
                  (i.e. maps a rectangle from feature space to image space)
        !*/</font>

    <b>}</b>;

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> T1,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> T2,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> T3,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>char</u></font> T4,
        <font color='#0000FF'><u>int</u></font>           T5
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='serialize'></a>serialize</b> <font face='Lucida Console'>(</font>
        <font color='#0000FF'>const</font> fine_hog_image<font color='#5555FF'>&lt;</font>T1,T2,T3,T4,T5<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> item,
        std::ostream<font color='#5555FF'>&amp;</font> out
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        provides serialization support 
    !*/</font>

    <font color='#0000FF'>template</font> <font color='#5555FF'>&lt;</font>
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> T1,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> T2,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>long</u></font> T3,
        <font color='#0000FF'><u>unsigned</u></font> <font color='#0000FF'><u>char</u></font> T4,
        <font color='#0000FF'><u>int</u></font>           T5
        <font color='#5555FF'>&gt;</font>
    <font color='#0000FF'><u>void</u></font> <b><a name='deserialize'></a>deserialize</b> <font face='Lucida Console'>(</font>
        fine_hog_image<font color='#5555FF'>&lt;</font>T1,T2,T3,T4,T5<font color='#5555FF'>&gt;</font><font color='#5555FF'>&amp;</font> item,
        std::istream<font color='#5555FF'>&amp;</font> in 
    <font face='Lucida Console'>)</font>;
    <font color='#009900'>/*!
        provides deserialization support 
    !*/</font>

<font color='#009900'>// ----------------------------------------------------------------------------------------
</font>
<b>}</b>

<font color='#0000FF'>#endif</font> <font color='#009900'>// DLIB_FINE_HOG_IMaGE_ABSTRACT_Hh_
</font>

</pre></body></html>